Expand description
§Serde YML
§Seamless YAML Serialization for Rust
Serde YML is a Rust library that simplifies YAML serialization and deserialization using the popular Serde framework. It provides a convenient and efficient way to convert Rust data structures to YAML format and vice versa.
§Features
- Serialization and deserialization of Rust data structures to/from YAML format
- Support for custom structs and enums using Serde’s derive macros
- Handling of YAML’s
!tag
syntax for representing enum variants - Direct access to YAML values through the
Value
type and related types likeMapping
andSequence
- Comprehensive error handling with
Error
,Location
, andResult
types - Serialization to YAML using
to_string
andto_writer
functions - Deserialization from YAML using
from_str
,from_slice
, andfrom_reader
functions - Customizable serialization and deserialization behavior using Serde’s
#[serde(with = ...)]
attribute - Support for serializing/deserializing enums using a YAML map with a single key-value pair through the
singleton_map
module - Recursive application of
singleton_map
serialization/deserialization to all enums within a data structure using thesingleton_map_recursive
module - Serialization and deserialization of optional enum fields using the
singleton_map_optional
module - Handling of nested enum structures with optional inner enums using the
singleton_map_recursive
module - Customization of serialization and deserialization logic for enums using the
singleton_map_with
module and custom helper functions
§Rust Version Compatibility
This library is compatible with Rust 1.60 and above.
§Installation
Add the following dependency to your Cargo.toml
file:
[dependencies]
serde_yml = "0.0.7"
§Usage
Serde YML offers a straightforward and intuitive API for working with YAML data in Rust. Here’s a quick example of how to serialize and deserialize a Rust type:
use serde::{Serialize, Deserialize};
#[derive(Serialize, Deserialize,Debug,PartialEq)]
struct Point {
x: f64,
y: f64,
}
fn main() -> Result<(), serde_yml::Error> {
let point = Point { x: 1.0, y: 2.0 };
// Serialize to YAML
let yaml = serde_yml::to_string(&point)?;
assert_eq!(yaml, "x: 1.0\n'y': 2.0\n");
// Deserialize from YAML
let deserialized_point: Point = serde_yml::from_str(&yaml)?;
assert_eq!(point, deserialized_point);
Ok(())
}
§Examples
Serde YML provides a set of comprehensive examples to demonstrate its usage and capabilities. You can find them in the examples
directory of the project.
To run the examples, clone the repository and execute the following command in your terminal from the project root directory:
cargo run --example example
The examples cover various scenarios, including serializing and deserializing structs, enums, optional fields, custom structs, and more.
§Best Practices and Common Pitfalls
- When serializing large datasets, consider using
serde_yml::to_writer
to write the YAML output directly to a file or a writer instead of keeping the entire serialized string in memory. - Be cautious when deserializing untrusted YAML input, as it may contain unexpected or malicious data. Always validate and handle the deserialized data appropriately.
- When working with custom structs or enums, ensure that they implement the necessary Serde traits (
Serialize
andDeserialize
) for proper serialization and deserialization. - If you encounter any issues or have questions, refer to the library’s documentation and examples for guidance. If the problem persists, consider opening an issue on the library’s GitHub repository.
§Credits and Acknowledgements
Serde YML draws inspiration from the excellent work done by David Tolnay and the maintainers of the serde-yaml library. While Serde YML started as a fork of serde-yaml, it has now evolved into a separate library with its own goals and direction in mind.
If you are currently using serde-yaml in your projects, we recommend carefully evaluating your requirements and considering the stability and maturity of the original library before migrating to Serde YML.
Finally, we would like to express our sincere gratitude to David Tolnay and the serde-yaml team for their valuable contributions to the Rust community and for inspiring this project.
Re-exports§
pub use crate::de::from_reader;
pub use crate::de::from_slice;
pub use crate::de::from_str;
pub use crate::de::Deserializer;
pub use crate::modules::error::Error;
pub use crate::modules::error::Location;
pub use crate::modules::error::Result;
pub use crate::ser::to_string;
pub use crate::ser::to_writer;
pub use crate::ser::Serializer;
pub use crate::ser::State;
Modules§
- The
de
module contains the library’s YAML deserializer. - The
libyml
module contains the library’s YAML parser and emitter. - The
loader
module contains theLoader
type for YAML loading. - The
macros
module contains functions for generating macros. - The
mapping
module contains theMapping
type for YAML mappings. A YAML mapping and its iterator types. - The
modules
module contains the library’s modules. - The
number
module contains theNumber
type for YAML numbers. - The
ser
module contains the library’s YAML serializer. YAML Serialization - The
utilities
module contains utility functions for the library. - The
value
module contains theValue
type for YAML values. The Value enum, a loosely typed way of representing any valid YAML value. - The
with
module contains theWith
type for YAML values. Customizations to use with Serde’s#[serde(with = …)]
attribute.
Macros§
- Macro
from_number
to implement conversion from number types toValue
. - A macro that generates a file based on a provided value, a generator function, and an optional custom serializer.
macro_check_directory
Macromacro_cleanup_directories
Macromacro_create_directories
Macro- Macro to generate a function that retrieves a field value from a JSON file.
- Custom logging macro for various log levels and formats.
- Replaces placeholders in a given line with corresponding values from the provided parameters.
- A macro that deserializes a nested singleton map from a YAML format.
- A macro that serializes a nested singleton map to a YAML format.
- A macro that generates implementations of the
PartialEq
trait for primitive numeric types andValue
based on the specified conversion method and base type.
Structs§
- A YAML mapping in which the keys and values are both
serde_yml::Value
. - Represents a YAML number, whether integer or floating point.
Enums§
- Represents any valid YAML value.
Traits§
- A type that can be used to index into a
serde_yml::Value
. See theget
andget_mut
methods ofValue
.
Functions§
- Interpret a
serde_yml::Value
as an instance of typeT
. - Converts a serializable value into a
serde_yml::Value
.
Type Aliases§
- A YAML sequence in which the elements are
serde_yml::Value
.